home *** CD-ROM | disk | FTP | other *** search
/ HPAVC / HPAVC CD-ROM.iso / NISTINFO.ZIP / NIST-SPHERE
Text File  |  1993-07-19  |  9KB  |  292 lines
  1.                        NIST SPHERE Header Structure
  2.  
  3.  
  4. The NIST SPHERE header is an object-oriented, 1024-byte blocked, ASCII 
  5. structure which is prepended to the waveform data.  The header is composed 
  6. of a fixed-format portion followed by an object-oriented variable portion.  
  7. The fixed portion is as follows:
  8.  
  9. NIST_1A<new-line>
  10.    1024<new-line>
  11.  
  12. The first line specifies the header type and the second line specifies the
  13. header length.  Each of these lines are 8 bytes long (including new-line) and
  14. are structured to identify the header as well as allow those who do not wish
  15. to read the subsequent header information to programmatically skip over it. 
  16.  
  17.  
  18. The remaining object-oriented variable portion is composed of
  19. object-type-value "triple" lines which have the following format:
  20.  
  21.  
  22. <LINE> ::= <TRIPLE><new-line> |
  23.            <COMMENT><new-line> | 
  24.            <TRIPLE><COMMENT><new-line> | 
  25.  
  26.   <TRIPLE> ::= <OBJECT><space><TYPE><space><VALUE><OPT-SPACES>
  27.  
  28.     <OBJECT> ::= <PRIMARY-SUBOBJECT> | 
  29.                  <PRIMARY-SUBOBJECT><SECONDARY-SUBOBJECT>
  30.  
  31.     <PRIMARY-SUBOBJECT> ::= <ALPHA> | <ALPHA><ALPHA-NUM-STRING>
  32.     <SECONDARY-SUBOBJECT> ::= _<ALPHA-NUM-STRING> | 
  33.                               _<ALPHA-NUM-STRING><SECONDARY-SUBOBJECT>
  34.  
  35.     <TYPE> ::= -<INTEGER-FLAG> | -<REAL-FLAG> | -<STRING-FLAG>
  36.  
  37.       <INTEGER-FLAG> ::= i
  38.       <REAL-FLAG> ::= r
  39.       <STRING-FLAG> ::= s<DIGIT-STRING>
  40.       
  41.     <VALUE> ::= <INTEGER> | <REAL> | <STRING>  (depending on object type)
  42.  
  43.       <INTEGER> ::= <SIGN><DIGIT-STRING>
  44.       <REAL> ::= <SIGN><DIGIT-STRING>.<DIGIT-STRING> 
  45.  
  46.     <OPT-SPACES> ::= <SPACES> | NULL
  47.  
  48.   <COMMENT> ::= ;<STRING>  (excluding embedded new-lines)
  49.  
  50. <ALPHA-NUM-STRING> ::= <ALPHA-NUM> | <ALPHA-NUM><ALPHA-NUM-STRING>
  51. <ALPHA-NUM> ::= <DIGIT> | <ALPHA>
  52. <ALPHA> ::= a | ... | z | A | ... | Z
  53. <DIGIT-STRING> ::= <DIGIT> | <DIGIT><DIGIT-STRING>
  54. <DIGIT> ::= 0 | ... | 9
  55. <SIGN> ::= + | - | NULL
  56. <SPACES> ::= <space> | <SPACES><space>
  57. <STRING> ::=  <CHARACTER> | <CHARACTER><STRING>
  58. <CHARACTER> ::= char(0) | char(1) | ... | char(255)
  59.  
  60. The currently defined objects (used in this database) are listed
  61. in the file "stdfield.c".  The list may be expanded for future
  62. databases, since the grammar does not impose any limit on the number
  63. of objects. The file is simply a repository for "standard" object
  64. definitions.
  65.  
  66. The single object "end_head" marks the end of the active header and the
  67. remaining unused header space is undefined. A sample header is included
  68. below.
  69.  
  70.                     -- John Garofolo
  71.  
  72.  
  73.  
  74.  
  75. NIST_1A
  76.    1024
  77. database_id -s5 TIMIT
  78. database_version -s3 1.0
  79. utterance_id -s8 aks0_sa1
  80. channel_count -i 1
  81. sample_count -i 63488
  82. sample_rate -i 16000
  83. sample_min -i -6967
  84. sample_max -i 7710
  85. sample_n_bytes -i 2
  86. sample_byte_format -s2 01
  87. sample_sig_bits -i 16
  88. end_head
  89.  
  90.  
  91.                                    SPHERE
  92.                         NIST SPeech HEader REsources
  93.  
  94.                              Release 1.7 (beta)
  95.                                  June 1991
  96.  
  97. 0. Introduction:
  98.  
  99. SPHERE is a software package containing:
  100.     1. a set of C functions that can be used to:
  101.         a) create and modify NIST speech file headers (in memory)
  102.         b) read (write) NIST speech file headers from (to) disk
  103.     2. a set of basic utility programs that use the functions
  104.  
  105. This software has been developed for use within the DARPA speech research
  106. community.  Although care has been taken to ensure that all software is
  107. complete and bug-free, it is made available to the speech research
  108. community without endorsement or express or implied warranties.  
  109.  
  110.  
  111.  
  112. 1. Usage:
  113.  
  114. User programs are linked with the library libsp.a, which contains
  115. the C functions mentioned above and some other functions that are
  116. used to support them. Functions that begin with "sp_" are intended
  117. to be callable by user programs. The semantics of the functions
  118. in this library are described in a manual page and comments in the
  119. source code.
  120.  
  121. All functions in the library that return pointers will return NULL
  122. pointers on failure/error. All numeric functions will return negative
  123. values on failure/error.
  124.  
  125. User programs that call the functions should "#include" the files
  126. header.h and sp.h. The former contains, among other things, some
  127. type definitions used by the library functions. The latter contains
  128. declarations for all user functions in the library.
  129.  
  130.  
  131.  
  132. 2. Installation:
  133.  
  134. To install SPHERE on a Unix system, use the Unix utility "make".
  135. While in the directory where the package source code has been
  136. installed, type:
  137.  
  138.     make -f makefile.
  139.  
  140. The speech header library will be created, as well as the sample
  141. programs. Installation on non-Unix systems without "make" will
  142. probably require manual compilation.
  143.  
  144.  
  145.  
  146. 3. Sample Programs:
  147.  
  148. Several sample programs have been included in this release to
  149. demonstrate the functionality of the SPHERE header library:
  150. Manual pages exist for "h_read" and "h_edit". Short descriptions
  151. of the others follow:
  152.  
  153.     h_add { inputfile | - } { outputfile | - }
  154.         adds a header to the data in inputfile, stores
  155.         the result in outputfile; a dash instead in place
  156.         of inputfile means read from stdin; a dash in
  157.         outputfile means write to stdout
  158.  
  159.     h_strip { inputfile | - } { outputfile | - }
  160.         strips the header from inputfile, stores the
  161.         remaining data in outputfile
  162.  
  163.     h_test
  164.         tests the header routines through an endless
  165.         loop that stores and retrieves values from a header;
  166.         Bugs in the library would hopefully either result
  167.         in an insertion/retrieval error or a memory allocation
  168.         error/failure
  169.  
  170.     h_nlrm
  171.         remove newline characters from fields
  172.  
  173.     h_delete
  174.         delete header fields
  175.  
  176. The abstract data type that programs use is a pointer to a "header_t"
  177. structure. This pointer is a handle used by the functions that operate
  178. on the header, much like a FILE pointer is used as a handle by functions
  179. in the C "stdio" library that operate on files.
  180.  
  181. One difference is that there are two different ways to return a
  182. header pointer to a user program. The first method is to call the
  183. function that returns a pointer to an empty header. The second
  184. reads the fields from a speech file into a header.
  185.  
  186. Another difference is that there is no set limit on the number of
  187. headers a program can have existing in memory at a given time.
  188. The C "stdio" library typically limits the number of open files
  189. to between 20 and 100, because the actual array of FILE structures
  190. is declared statically. Header structures are allocated dynamically,
  191. so user programs should deallocate headers that are no longer in
  192. use to avoid running out of memory.
  193.  
  194.  
  195.  
  196. 4. Documentation:
  197.  
  198. The following documentation files are also located in this directory:
  199.  
  200.  changes.doc - list of recent modifications to SPHERE
  201. disclaim.doc - NIST software disclaimer
  202.   header.doc - description of NIST header structure
  203.   readme.doc - this file
  204.  
  205.     h_read.1 - manual page for the command "h_read"
  206.   h_read.doc - simple text version of "h_read.1"
  207.  
  208.     h_edit.1 - manual page for the command "h_edit"
  209.   h_edit.doc - simple text version of "h_edit.1"
  210.  
  211.     sphere.3 - manual page for the SPHERE function library
  212.   sphere.doc - simple text version of "sphere.3"
  213.  
  214.  
  215.  
  216. 5. Bug Reports:
  217.  
  218. Please report any bugs to John Garofolo by sending email to
  219. john@jaguar.ncsl.nist.gov.
  220.  
  221. Please include a description of the bug/problem and the hardware
  222. and software under which the problem occurred, as well as any data
  223. needed to reproduce the problem.
  224.  
  225. The most recent version of the SPHERE package is available
  226. via anonymous ftp from jaguar.ncsl.nist.gov [129.6.48.157] in
  227. compressed tar form as "sphere-v.tar.Z" (where "v" is the version
  228. code).
  229.  
  230. 6. Changes in Release 1.5:
  231.  
  232.     1. New functions were added to the Sphere library:
  233.         sp_get_fieldnames()
  234.         sp_get_type()
  235.         sp_get_size()
  236.         sp_is_std()
  237.  
  238.         (see the sphere library man page for descriptions)
  239.  
  240.     2. h_read: command line options were changed
  241.  
  242.     3. h_strip: writes to stdout if destination is "-"
  243.  
  244.     4. man page for h_read
  245.  
  246.  
  247. 7. Changes in Release 1.6:
  248.  
  249.     1. Utilities that use h_modify.c are now much faster in
  250.         most cases when editing in-place -- if the size
  251.         of the header does not change, the new header is
  252.         copied over the old one.
  253.  
  254.     2. Modified sp_write_header() to work when writing to
  255.         objects other than files. The function ftell()
  256.         was previously used directly on the output
  257.         stream to ascertain the number of bytes
  258.         in the header; now the header is written
  259.         to a temp file to ascertain the header size,
  260.         then to the output stream.
  261.  
  262.     3. Modified to sp_open_header() and spx_read_header()
  263.         to no longer test if the input file is at
  264.         position 0. This will allow reading from
  265.         pipes, etc.
  266.  
  267.     4. h_add: can read from stdin and/or write to stdout;
  268.         no longer puts any dummy fields in the header.
  269.  
  270.  
  271.     5. h_strip: can now read from stdin in addition to
  272.         writing to stdout.
  273.  
  274.     6. Added h_header and raw2nist to the Sphere package.
  275.         They are Bourne shell scripts (/bin/sh) to,
  276.         respectively, print file headers and convert raw
  277.         data (no header) to Sphere format.
  278.  
  279.     7. Manual pages for commands h_edit, h_delete, h_add,
  280.         h_strip and raw2nist
  281.  
  282. 8. Changes in Release 1.7:
  283.  
  284.     1. h_read: added "-C field" option to check that the
  285.         specified field(s) is in the headers of all files
  286.         on the command line.
  287.  
  288.  
  289. --------------------------
  290.   Stan Janet
  291.   stan@jaguar.ncsl.nist.gov
  292.